Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Images

FDecompressImage

Like the DecompressImage function, the FDecompressImage function allows your application to decompress a single-frame image into a pixel map (PixMap). This function gives your application greater control over the parameters that guide the decompression operation. If you find that you do not need this level of control, use the DecompressImage function, described in the previous section.

pascal OSErr FDecompressImage (Ptr data, 
                              ImageDescriptionHandle desc,
                              PixMapHandle dst, 
                              const  Rect *srcRect,
                              MatrixRecordPtr matrix, 
                              short mode, RgnHandle mask,
                              PixMapHandle matte, 
                              const  Rect *matteRect, 
                              CodecQ accuracy,
                              DecompressorComponent codec, 
                              long bufferSize, 
                              DataProcRecordPtr dataProc,
                              ProgressProcRecordPtr progressProc);

data

Points to the compressed image data. If the entire compressed image cannot be stored at this location, your application may provide a data-loading function (see the discussion of the dataProc parameter to this function). This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter. (See Inside Macintosh: Memory for details on StripAddress.)

desc

Contains a handle to the image description structure that describes the compressed image.

dst

Contains a handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

srcRect

Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to nil. If the parameter is
nil, the rectangle is set to the rectangle structure of the image description structure.

matrix

Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to nil. See the chapter "Movie Toolbox" in this book for more information about matrix operations.

mode

Specifies the transfer mode for the operation. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine (described in Inside Macintosh: Imaging).

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to nil.

matte

Contains a handle to a pixel map that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported
pixel depth--the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you do not want to apply a blend matte, set this parameter to nil.

matteRect

Contains a pointer to a rectangle defining a portion of the blend matte to apply. If you do not want to use the entire matte referred to by the matte parameter, use this parameter to specify a rectangle within that matte. If specified, this rectangle must be the same size as the rectangle specified by the srcRect parameter. If you want to use the entire matte, or if you are not providing a blend matte, set this parameter to nil.

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants" beginning on page 3-52 for valid values. (For a good display of still images, you should specify at least the codecHighQuality constant.)

codec

Contains a compressor identifier. Specify a particular decompressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first decompressor of the specified type

bestSpeedCodec

Choose the fastest decompressor of the specified type

bestFidelityCodec

Choose the most accurate decompressor of the specified type

bestCompressionCodec

Choose the decompressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec, the Image Compression Manager chooses the first decompressor it finds of the specified type.

bufferSize

Specifies the size of the buffer to be used by the data-loading
function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

dataProc

Points to a data-loading function structure. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data (see "Data-Loading Functions" on page 3-153 for more information about data-loading functions). If you have not provided a data-loading function, set this parameter to nil. In this case, the compressor expects that the entire compressed image is in the memory location specified by the data parameter.

progressProc

Points to a progress function structure. During the decompression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" on page 3-156 for more information about progress functions). If you have not provided a progress function, set this parameter to nil. If you pass a value of -1, you obtain a standard progress function.

DESCRIPTION

Note that this function is invoked through the StdPix function (see "Working With the StdPix Function," which begins on page 3-141, for more information).

SPECIAL CONSIDERATIONS

The graphics port and the graphics device should be set to the destination before you call the FDecompressImage function.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecSpoolErr	-8966	Error loading or unloading data
codecAbortErr	-8967	Operation aborted by the progress function